home *** CD-ROM | disk | FTP | other *** search
/ PC World 2006 July & August / PCWorld_2006-07-08_cd.bin / komunikace / apache / apache_2[1].2.2-win32-x86-no_ssl.msi / Data1.cab / _0A734324CE5D0B82DD187933890E1E8D < prev    next >
Text File  |  2006-04-08  |  8KB  |  227 lines
  1. /* Copyright 2000-2005 The Apache Software Foundation or its licensors, as
  2.  * applicable.
  3.  *
  4.  * Licensed under the Apache License, Version 2.0 (the "License");
  5.  * you may not use this file except in compliance with the License.
  6.  * You may obtain a copy of the License at
  7.  *
  8.  *     http://www.apache.org/licenses/LICENSE-2.0
  9.  *
  10.  * Unless required by applicable law or agreed to in writing, software
  11.  * distributed under the License is distributed on an "AS IS" BASIS,
  12.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13.  * See the License for the specific language governing permissions and
  14.  * limitations under the License.
  15.  */
  16.  
  17. #ifndef APR_HASH_H
  18. #define APR_HASH_H
  19.  
  20. /**
  21.  * @file apr_hash.h
  22.  * @brief APR Hash Tables
  23.  */
  24.  
  25. #include "apr_pools.h"
  26.  
  27. #ifdef __cplusplus
  28. extern "C" {
  29. #endif
  30.  
  31. /**
  32.  * @defgroup apr_hash Hash Tables
  33.  * @ingroup APR 
  34.  * @{
  35.  */
  36.  
  37. /**
  38.  * When passing a key to apr_hash_set or apr_hash_get, this value can be
  39.  * passed to indicate a string-valued key, and have apr_hash compute the
  40.  * length automatically.
  41.  *
  42.  * @remark apr_hash will use strlen(key) for the length. The NUL terminator
  43.  *         is not included in the hash value (why throw a constant in?).
  44.  *         Since the hash table merely references the provided key (rather
  45.  *         than copying it), apr_hash_this() will return the NUL-term'd key.
  46.  */
  47. #define APR_HASH_KEY_STRING     (-1)
  48.  
  49. /**
  50.  * Abstract type for hash tables.
  51.  */
  52. typedef struct apr_hash_t apr_hash_t;
  53.  
  54. /**
  55.  * Abstract type for scanning hash tables.
  56.  */
  57. typedef struct apr_hash_index_t apr_hash_index_t;
  58.  
  59. /**
  60.  * Callback functions for calculating hash values.
  61.  * @param key The key.
  62.  * @param klen The length of the key, or APR_HASH_KEY_STRING to use the string 
  63.  *             length. If APR_HASH_KEY_STRING then returns the actual key length.
  64.  */
  65. typedef unsigned int (*apr_hashfunc_t)(const char *key, apr_ssize_t *klen);
  66.  
  67. /**
  68.  * The default hash function.
  69.  */
  70. APR_DECLARE_NONSTD(unsigned int) apr_hashfunc_default(const char *key,
  71.                                                       apr_ssize_t *klen);
  72.  
  73. /**
  74.  * Create a hash table.
  75.  * @param pool The pool to allocate the hash table out of
  76.  * @return The hash table just created
  77.   */
  78. APR_DECLARE(apr_hash_t *) apr_hash_make(apr_pool_t *pool);
  79.  
  80. /**
  81.  * Create a hash table with a custom hash function
  82.  * @param pool The pool to allocate the hash table out of
  83.  * @param hash_func A custom hash function.
  84.  * @return The hash table just created
  85.   */
  86. APR_DECLARE(apr_hash_t *) apr_hash_make_custom(apr_pool_t *pool, 
  87.                                                apr_hashfunc_t hash_func);
  88.  
  89. /**
  90.  * Make a copy of a hash table
  91.  * @param pool The pool from which to allocate the new hash table
  92.  * @param h The hash table to clone
  93.  * @return The hash table just created
  94.  * @remark Makes a shallow copy
  95.  */
  96. APR_DECLARE(apr_hash_t *) apr_hash_copy(apr_pool_t *pool,
  97.                                         const apr_hash_t *h);
  98.  
  99. /**
  100.  * Associate a value with a key in a hash table.
  101.  * @param ht The hash table
  102.  * @param key Pointer to the key
  103.  * @param klen Length of the key. Can be APR_HASH_KEY_STRING to use the string length.
  104.  * @param val Value to associate with the key
  105.  * @remark If the value is NULL the hash entry is deleted.
  106.  */
  107. APR_DECLARE(void) apr_hash_set(apr_hash_t *ht, const void *key,
  108.                                apr_ssize_t klen, const void *val);
  109.  
  110. /**
  111.  * Look up the value associated with a key in a hash table.
  112.  * @param ht The hash table
  113.  * @param key Pointer to the key
  114.  * @param klen Length of the key. Can be APR_HASH_KEY_STRING to use the string length.
  115.  * @return Returns NULL if the key is not present.
  116.  */
  117. APR_DECLARE(void *) apr_hash_get(apr_hash_t *ht, const void *key,
  118.                                  apr_ssize_t klen);
  119.  
  120. /**
  121.  * Start iterating over the entries in a hash table.
  122.  * @param p The pool to allocate the apr_hash_index_t iterator. If this
  123.  *          pool is NULL, then an internal, non-thread-safe iterator is used.
  124.  * @param ht The hash table
  125.  * @remark  There is no restriction on adding or deleting hash entries during
  126.  * an iteration (although the results may be unpredictable unless all you do
  127.  * is delete the current entry) and multiple iterations can be in
  128.  * progress at the same time.
  129.  
  130.  * @example
  131.  */
  132. /**
  133.  * <PRE>
  134.  * 
  135.  * int sum_values(apr_pool_t *p, apr_hash_t *ht)
  136.  * {
  137.  *     apr_hash_index_t *hi;
  138.  *     void *val;
  139.  *     int sum = 0;
  140.  *     for (hi = apr_hash_first(p, ht); hi; hi = apr_hash_next(hi)) {
  141.  *         apr_hash_this(hi, NULL, NULL, &val);
  142.  *         sum += *(int *)val;
  143.  *     }
  144.  *     return sum;
  145.  * }
  146.  * </PRE>
  147.  */
  148. APR_DECLARE(apr_hash_index_t *) apr_hash_first(apr_pool_t *p, apr_hash_t *ht);
  149.  
  150. /**
  151.  * Continue iterating over the entries in a hash table.
  152.  * @param hi The iteration state
  153.  * @return a pointer to the updated iteration state.  NULL if there are no more  
  154.  *         entries.
  155.  */
  156. APR_DECLARE(apr_hash_index_t *) apr_hash_next(apr_hash_index_t *hi);
  157.  
  158. /**
  159.  * Get the current entry's details from the iteration state.
  160.  * @param hi The iteration state
  161.  * @param key Return pointer for the pointer to the key.
  162.  * @param klen Return pointer for the key length.
  163.  * @param val Return pointer for the associated value.
  164.  * @remark The return pointers should point to a variable that will be set to the
  165.  *         corresponding data, or they may be NULL if the data isn't interesting.
  166.  */
  167. APR_DECLARE(void) apr_hash_this(apr_hash_index_t *hi, const void **key, 
  168.                                 apr_ssize_t *klen, void **val);
  169.  
  170. /**
  171.  * Get the number of key/value pairs in the hash table.
  172.  * @param ht The hash table
  173.  * @return The number of key/value pairs in the hash table.
  174.  */
  175. APR_DECLARE(unsigned int) apr_hash_count(apr_hash_t *ht);
  176.  
  177. /**
  178.  * Merge two hash tables into one new hash table. The values of the overlay
  179.  * hash override the values of the base if both have the same key.  Both
  180.  * hash tables must use the same hash function.
  181.  * @param p The pool to use for the new hash table
  182.  * @param overlay The table to add to the initial table
  183.  * @param base The table that represents the initial values of the new table
  184.  * @return A new hash table containing all of the data from the two passed in
  185.  */
  186. APR_DECLARE(apr_hash_t *) apr_hash_overlay(apr_pool_t *p,
  187.                                            const apr_hash_t *overlay, 
  188.                                            const apr_hash_t *base);
  189.  
  190. /**
  191.  * Merge two hash tables into one new hash table. If the same key
  192.  * is present in both tables, call the supplied merge function to
  193.  * produce a merged value for the key in the new table.  Both
  194.  * hash tables must use the same hash function.
  195.  * @param p The pool to use for the new hash table
  196.  * @param h1 The first of the tables to merge
  197.  * @param h2 The second of the tables to merge
  198.  * @param merger A callback function to merge values, or NULL to
  199.  *  make values from h1 override values from h2 (same semantics as
  200.  *  apr_hash_overlay())
  201.  * @param data Client data to pass to the merger function
  202.  * @return A new hash table containing all of the data from the two passed in
  203.  */
  204. APR_DECLARE(apr_hash_t *) apr_hash_merge(apr_pool_t *p,
  205.                                          const apr_hash_t *h1,
  206.                                          const apr_hash_t *h2,
  207.                                          void * (*merger)(apr_pool_t *p,
  208.                                                      const void *key,
  209.                                                      apr_ssize_t klen,
  210.                                                      const void *h1_val,
  211.                                                      const void *h2_val,
  212.                                                      const void *data),
  213.                                          const void *data);
  214.  
  215. /**
  216.  * Get a pointer to the pool which the hash table was created in
  217.  */
  218. APR_POOL_DECLARE_ACCESSOR(hash);
  219.  
  220. /** @} */
  221.  
  222. #ifdef __cplusplus
  223. }
  224. #endif
  225.  
  226. #endif    /* !APR_HASH_H */
  227.